Skip to content

API Explorer: omit empty authentication and servers pages - #4118

Open
reakaleek wants to merge 4 commits into
mainfrom
feat/hide-empty-api-servers
Open

reakaleek wants to merge 4 commits into
mainfrom
feat/hide-empty-api-servers

Conversation

@reakaleek

@reakaleek reakaleek commented Sep 16, 2026

Copy link
Copy Markdown
Member

An API product with no servers or no security schemes no longer gets an empty Servers or Authentication page.

Affects: API reference, Isolated builds

Prompt summary: Hide the servers page when the API spec does not declare servers, instead of showing "This API does not declare servers." Also hide the authentication page when the spec has no schemes, matching how bump.sh keeps Authentications out of an empty state and keeps Servers out of the sidebar.

Why

  • Specs that omit servers still produced a /servers page whose body is "This API does not declare servers."
  • Bump.sh on elastic.co/docs/api leaves that URL as an empty page and does not list Servers in Topics. We omit the page so the URL 404s instead of shipping a dead document.
  • Specs that omit security schemes had the same empty Authentication page. Bump.sh lists Authentications when schemes exist. We omit the page when they do not.

What

  • StructuralNavigationItem.Create adds Authentication only when HasSchemes is true, and Servers only when ReadServers is non-empty.
  • The generator then writes no HTML or markdown for the omitted kinds.
  • authentication and servers stay reserved child slugs even when those pages are omitted.

Notes

  • Setting Hidden would still write the page. OpenApiGenerator.RenderNavigationItems walks every leaf.
  • We do not copy bump.sh's empty 200 /servers URL.

Verify

dotnet test tests/Elastic.ApiExplorer.Tests/
# Create_EmptyDocument_OmitsAuthenticationAndServersPages
# Create_NoSchemes_OmitsAuthenticationPage
# Create_NoServers_OmitsServersPage
# Generate_WritesDistinctOutputTreesForMainAndReleasedMajors

An empty servers page is noise for readers. Presence now follows ReadServers.

Co-Authored-By: Cursor Grok 4.6 <noreply@anthropic.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
The next lines already add the generated OpenAPI items.

Co-Authored-By: Cursor Grok 4.6 <noreply@anthropic.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
@github-actions

Copy link
Copy Markdown
Contributor

Docs preview (local build)

Handbook preview: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/4118/

Sample changed pages:

Comment thread docs/data/openapi/api-explorer.md Outdated
Bump.sh keeps Authentications in the sidebar only when schemes exist. An empty Authentication page is the same dead end as an empty Servers page.

Co-Authored-By: Cursor Grok 4.6 <noreply@anthropic.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
@reakaleek reakaleek changed the title API Explorer: hide servers page when spec has none API Explorer: omit empty authentication and servers pages Sep 16, 2026
…-actions)

ReservedChildSegments still rejects servers and authentication unconditionally.

Co-Authored-By: Cursor Grok 4.6 <noreply@anthropic.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

This branch was successfully deployed

2 active deployments
assembler-preview 3ff7bfb4 Deployed Sep 16, 2026 by github-actions[bot]
docs-preview 3ff7bfb4 Deployed Sep 16, 2026 by github-actions[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant